home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / gawk213b.zoo / strftime.man < prev   
Text File  |  1991-08-04  |  6KB  |  183 lines
  1.  
  2.  
  3.  
  4. STRFTIME(3)         UNIX Programmer's Manual          STRFTIME(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      strftime - generate formatted time information
  10.  
  11. SYNOPSIS
  12.      #include <sys/types.h>
  13.      #include <time.h>
  14.  
  15.      size_t strftime(char *s, size_t maxsize, const char *format,
  16.           const struct tm *timeptr);
  17.  
  18. DESCRIPTION
  19.      The following description is transcribed verbatim from the
  20.      December 7, 1988 draft standard for ANSI C.  This draft is
  21.      essentially identical in technical content to the final ver-
  22.      sion of the standard.
  23.  
  24.      The strftime function places characters into the array
  25.      pointed to by s as controlled by the string pointed to by
  26.      format.  The format shall be a multibyte character sequence,
  27.      beginning and ending in its initial shift state.  The format
  28.      string consists of zero or more conversion specifiers and
  29.      ordinary multibyte characters.  A conversion specifier con-
  30.      sists of a % character followed by a character that deter-
  31.      mines the behavior of the conversion specifier.  All ordi-
  32.      nary multibyte characters (including the terminating null
  33.      character) are copied unchanged into the array.  If copying
  34.      takes place between objects that overlap the behavior is
  35.      undefined.  No more than maxsize characters are placed into
  36.      the array.  Each conversion specifier is replaced by
  37.      appropriate characters as described in the following list.
  38.      The appropriate characters are determined by the LC_TIME
  39.      category of the current locale and by the values contained
  40.      in the structure pointed to by timeptr.
  41.  
  42.      %a   is replaced by the locale's abbreviated weekday name.
  43.  
  44.      %A   is replaced by the locale's full weekday name.
  45.  
  46.      %b   is replaced by the locale's abbreviated month name.
  47.  
  48.      %B   is replaced by the locale's full month name.
  49.  
  50.      %c   is replaced by the locale's appropriate date and time
  51.           representation.
  52.  
  53.      %d   is replaced by the day of the month as a decimal number
  54.           (01-31).
  55.  
  56.      %H   is replaced by the hour (24-hour clock) as a decimal
  57.           number (00-23).
  58.  
  59.      %I   is replaced by the hour (12-hour clock) as a decimal
  60.           number (01-12).
  61.  
  62.      %j   is replaced by the day of the year as a decimal number
  63.           (001-366).
  64.  
  65.      %m   is replaced by the month as a decimal number (01-12).
  66.  
  67.      %M   is replaced by the minute as a decimal number (00-59).
  68.  
  69.      %p   is replaced by the locale's equivalent of the AM/PM
  70.           designations associated with a 12-hour clock.
  71.  
  72.      %S   is replaced by the second as a decimal number (00-61).
  73.  
  74.      %U   is replaced by the week number of the year (the first
  75.           Sunday as the first day of week 1) as a decimal number
  76.           (00-53).
  77.  
  78.      %w   is replaced by the weekday as a decimal number [0
  79.           (Sunday)-6].
  80.  
  81.      %W   is replaced by the week number of the year (the first
  82.           Monday as the first day of week 1) as a decimal number
  83.           (00-53).
  84.  
  85.      %x   is replaced by the locale's appropriate date represen-
  86.           tation.
  87.  
  88.      %X   is replaced by the locale's appropriate time represen-
  89.           tation.
  90.  
  91.      %y   is replaced by the year without century as a decimal
  92.           number (00-99).
  93.  
  94.      %Y   is replaced by the year with century as a decimal
  95.           number.
  96.  
  97.      %Z   is replaced by the time zone name or abbreviation, or
  98.           by no characters if no time zone is determinable.
  99.  
  100.      %%   is replaced by %.
  101.  
  102.      If a conversion specifier is not one of the above, the
  103.      behavior is undefined.
  104.  
  105. RETURNS
  106.      If the total number of resulting characters including the
  107.      terminating null character is not more than maxsize, the
  108.      strftime function returns the number of characters placed
  109.      into the array pointed to by s not including the terminating
  110.      null character.  Otherwise, zero is returned and the con-
  111.      tents of the array are indeterminate.
  112.  
  113. NON-ANSI EXTENSIONS
  114.      If SYSV_EXT is defined when the routine is compiled, then
  115.      the following additional conversions will be available.
  116.      These are borrowed from the System V cftime(3) and ascf-
  117.      time(3) routines.
  118.  
  119.      %D   is equivalent to specifying %m/%d/%y.
  120.  
  121.      %e   is replaced by the day of the month, padded with a
  122.           blank if it is only one digit.
  123.  
  124.      %h   is equivalent to %b, above.
  125.  
  126.      %n   is replaced with a newline character (ASCII LF).
  127.  
  128.      %r   is equivalent to specifying %I:%M:%S %p.
  129.  
  130.      %R   is equivalent to specifying %H:%M:.
  131.  
  132.      %T   is equivalent to specifying %H:%M:%S.
  133.  
  134.      %t   is replaced with a TAB character.
  135.  
  136. POSIX 1003.2 EXTENSIONS
  137.      If POSIX2_DATE is defined, then all of the conversions
  138.      available with SYSV_EXT are available, as well as the fol-
  139.      lowing additional conversions:
  140.  
  141.      %C   The century, as a number between 00 and 99.
  142.  
  143.      In additon, the alternate representations %Ec, %EC, %Ex,
  144.      %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %OU, %Ow, %OW,
  145.      and %Oy are recognized, but their normal representations are
  146.      used.
  147.  
  148. SEE ALSO
  149.      time(2), ctime(3), localtime(3)
  150.  
  151. BUGS
  152.      This version does not handle multibyte characters or pay
  153.      attention to the setting of the LC_TIME environment vari-
  154.      able.
  155.  
  156.      It is not clear what is ``appropriate'' for the C locale;
  157.      the values returned are a best guess on the author's part.
  158.  
  159. CAVEATS
  160.      This implementation calls tzset(3) exactly once.  If the TZ
  161.      environment variable is changed after strftime has been
  162.      called, then tzset(3) must be called again, explicitly, in
  163.      order for the correct timezone information to be available.
  164.  
  165. AUTHOR
  166.      Arnold Robbins
  167.      AudioFAX, Inc.
  168.      Suite 200
  169.      2000 Powers Ferry Road
  170.      Marietta, GA. 30067
  171.      U.S.A.
  172.      INTERNET: arnold@audiofax.com
  173.      UUCP:     emory!audfax!arnold
  174.      Phone:    +1 404 618 4281
  175.      Fax-box:  +1 404 618 4581
  176.  
  177. ACKNOWLEDGEMENTS
  178.      Thanks to Geoff Clare <gwc@root.co.uk> for helping debug
  179.      earlier versions of this routine.  Additional thanks to
  180.      Arthur David Olsen <ado@elsie.nci.nih.gov> for some code
  181.      improvements.
  182.  
  183.